<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Chapter 17. Advanced Features</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
<link rel="home" href="index.html" title="Smarty 3 Manual">
<link rel="up" href="smarty.for.programmers.html" title="Part III. Smarty For Programmers">
<link rel="prev" href="resources.custom.html" title="Custom Template Resources">
<link rel="next" href="advanced.features.template.settings.html" title="Changing settings by template">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr><th colspan="3" align="center">Chapter 17. Advanced Features</th></tr>
<tr>
<td width="20%" align="left">
<a accesskey="p" href="resources.custom.html">Prev</a> </td>
<th width="60%" align="center">Part III. Smarty For Programmers</th>
<td width="20%" align="right"> <a accesskey="n" href="advanced.features.template.settings.html">Next</a>
</td>
</tr>
</table>
<hr>
</div>
<div class="chapter" title="Chapter 17. Advanced Features">
<div class="titlepage"><div><div><h2 class="title">
<a name="advanced.features"></a>Chapter 17. Advanced Features</h2></div></div></div>
<div class="toc">
<p><b>Table of Contents</b></p>
<dl>
<dt><span class="sect1"><a href="advanced.features.html#advanced.features.security">Security</a></span></dt>
<dt><span class="sect1"><a href="advanced.features.template.settings.html">Changing settings by template</a></span></dt>
<dt><span class="sect1"><a href="advanced.features.template.inheritance.html">Template Inheritance</a></span></dt>
<dt><span class="sect1"><a href="advanced.features.streams.html">Streams</a></span></dt>
<dt><span class="sect1"><a href="advanced.features.objects.html">Objects</a></span></dt>
<dt><span class="sect1"><a href="advanced.features.static.classes.html">Static Classes</a></span></dt>
<dt><span class="sect1"><a href="advanced.features.prefilters.html">Prefilters</a></span></dt>
<dt><span class="sect1"><a href="advanced.features.postfilters.html">Postfilters</a></span></dt>
<dt><span class="sect1"><a href="advanced.features.outputfilters.html">Output Filters</a></span></dt>
</dl>
</div>
<div class="sect1" title="Security">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="advanced.features.security"></a>Security</h2></div></div></div>
<p>
   Security is good for situations when you have untrusted parties editing the templates
   eg via ftp, and you want to reduce the risk of system security compromises through the template language. 
 </p>
<p>
   The settings of the security policy are defined by properties of an instance of the Smarty_Security class.
These are the possible settings:
</p>
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<li class="listitem">
<p>
      <em class="parameter"><code>$php_handling</code></em> determines how Smarty to handle PHP code embedded in templates.
      Possible values are:
      </p>
<div class="itemizedlist"><ul class="itemizedlist" type="circle">
<li class="listitem"><p>
          Smarty::PHP_PASSTHRU -&gt; echo PHP tags as they are
          </p></li>
<li class="listitem"><p>
          Smarty::PHP_QUOTE    -&gt; escape tags as entities
          </p></li>
<li class="listitem"><p>
          Smarty::PHP_REMOVE   -&gt; remove php tags
          </p></li>
<li class="listitem"><p>
          Smarty::PHP_ALLOW    -&gt; execute php tags
          </p></li>
</ul></div>
<p>
      The default value is Smarty::PHP_PASSTHRU.
    </p>
<p>
      If security is enabled the <a class="link" href="variable.php.handling.html" title="$php_handling"><em class="parameter"><code>$php_handling</code></em></a>
      setting of the Smarty object is not checked for security.
    </p>
</li>
<li class="listitem"><p>
      <em class="parameter"><code>$secure_dir</code></em> is an array of template directories that are considered secure.
      <a class="link" href="variable.template.dir.html" title="$template_dir"><em class="parameter"><code>$template_dir</code></em></a> concidered secure implicitly.
      The default is an empty array.
    </p></li>
<li class="listitem"><p>
      <em class="parameter"><code>$trusted_dir</code></em> is an array of all directories that are considered trusted.
      Trusted directories are where you keep php scripts that are executed directly from the templates
      with <a class="link" href="language.function.include.php.html" title="{include_php}"><code class="varname">{include_php}</code></a>.
      The default is an empty array.
    </p></li>
<li class="listitem">
<p>
        <em class="parameter"><code>$trusted_uri</code></em> is an array of regular expressions matching URIs that are considered trusted.
        This security directive used by <a class="link" href="language.function.fetch.html" title="{fetch}"><code class="varname">{fetch}</code></a> and
        <a class="link" href="language.function.html.image.html" title="{html_image}"><code class="varname">{html_image}</code></a>. URIs passed to these functions
        are reduced to <code class="literal">{$PROTOCOL}://{$HOSTNAME}</code> to allow simple regular expressions 
        (without having to deal with edge cases like authentication-tokens).
      </p>
<p>
        The expression <code class="literal">'#https?://.*smarty.net$#i'</code> would allow accessing the follwing URIs:
        </p>
<div class="itemizedlist"><ul class="itemizedlist" type="circle">
<li class="listitem"><p><code class="literal">http://smarty.net/foo</code></p></li>
<li class="listitem"><p><code class="literal">http://smarty.net/foo</code></p></li>
<li class="listitem"><p><code class="literal">http://www.smarty.net/foo</code></p></li>
<li class="listitem"><p><code class="literal">http://smarty.net/foo</code></p></li>
<li class="listitem"><p><code class="literal">https://foo.bar.www.smarty.net/foo/bla?blubb=1</code></p></li>
</ul></div>
<p>

        but deny access to these URIs:

        </p>
<div class="itemizedlist"><ul class="itemizedlist" type="circle">
<li class="listitem"><p><code class="literal">http://smarty.com/foo</code> (not matching top-level domain "com")</p></li>
<li class="listitem"><p><code class="literal">ftp://www.smarty.net/foo</code> (not matching protocol "ftp")</p></li>
<li class="listitem"><p><code class="literal">http://www.smarty.net.otherdomain.com/foo</code> (not matching end of domain "smarty.net")</p></li>
</ul></div>
<p>
      </p>
</li>
<li class="listitem"><p>
      <em class="parameter"><code>$static_classes</code></em> is an array of classes that are considered trusted.
      The default is an empty array which allows access to all static classes. To disable access to
      all static classes set $static_classes = null.
    </p></li>
<li class="listitem"><p>
      <em class="parameter"><code>$php_functions</code></em> is an array of PHP functions that are considered trusted and 
      can be used from within template. To disable access to all PHP functions set $php_functions = null.
      An empty array ( $php_functions = array() ) will allow all PHP functions.
      The default is array('isset', 'empty', 'count', 'sizeof', 'in_array', 'is_array','time','nl2br').
    </p></li>
<li class="listitem"><p>
      <em class="parameter"><code>$php_modifiers</code></em> is an array of PHP functions that are considered trusted and 
      can be used from within template as modifier. To disable access to all PHP modifier set $php_modifier = null.
      An empty array ( $php_modifier = array() ) will allow all PHP functions.
      The default is array('escape','count').
    </p></li>
<li class="listitem"><p>
      <em class="parameter"><code>$streams</code></em> is an array of streams that are considered trusted and 
      can be used from within template. To disable access to all streams set $streams = null.
      An empty array ( $streams = array() ) will allow all streams.
      The default is array('file').
    </p></li>
<li class="listitem"><p>
     <em class="parameter"><code>$allowed_modifiers</code></em> is an array of (registered / autoloaded) 
     modifiers that should be accessible to the template. If this array is non-empty,
     only the herein listed modifiers may be used. This is a whitelist.
    </p></li>
<li class="listitem"><p>
     <em class="parameter"><code>$disabled_modifiers</code></em> is an array of (registered / autoloaded) 
     modifiers that may not be accessible to the template.
    </p></li>
<li class="listitem"><p>
     <em class="parameter"><code>$allowed_tags</code></em> is a boolean flag which controls if constants can
     function-, block and filter plugins that should be accessible to the template. If this 
     array is non-empty, only the herein listed modifiers may be used. This is a whitelist.
    </p></li>
<li class="listitem"><p>
     <em class="parameter"><code>$disabled_tags</code></em> is an array of (registered / autoloaded) 
     function-, block and filter plugins that may not be accessible to the template.
    </p></li>
<li class="listitem"><p>
     <em class="parameter"><code>$allow_constants</code></em> is a boolean flag which controls if constants can
     be accessed by the template. The default is "true".
    </p></li>
<li class="listitem"><p>
      <em class="parameter"><code>$allow_super_globals</code></em> is a boolean flag which controls if the PHP
      super globals can be accessed by the template. The default is "true".
    </p></li>
<li class="listitem"><p>
      <em class="parameter"><code>$allow_php_tag</code></em> is a boolean flag which controls if {php} and {include_php}
      tags can be used by the template. The default is "false".
    </p></li>
</ul></div>
<p>
 </p>
<p>
    If security is enabled, no private methods, functions or properties of static classes or assigned objects can be accessed
    (beginningwith '_') by the template. 
  </p>
<p>
    To customize the security policy settings you can extend the Smarty_Security class or create an instance of it.
 </p>
<div class="example">
<a name="id458178"></a><p class="title"><b>Example 17.1. Setting security policy by extending the Smarty_Security class</b></p>
<div class="example-contents"><pre class="programlisting">

&lt;?php
require 'Smarty.class.php';

class My_Security_Policy extends Smarty_Security {
  // disable all PHP functions
  public $php_functions = null;
  // remove PHP tags
  public $php_handling = Smarty::PHP_REMOVE;
  // allow everthing as modifier
  public $modifiers = array();
}
$smarty = new Smarty();
// enable security
$smarty-&gt;enableSecurity('My_Security_Policy');
?&gt;

</pre></div>
</div>
<br class="example-break"><div class="example">
<a name="id458192"></a><p class="title"><b>Example 17.2. Setting security policy by instance of the Smarty_Security class</b></p>
<div class="example-contents"><pre class="programlisting">

&lt;?php
require 'Smarty.class.php';
$smarty = new Smarty();
$my_security_policy = new Smarty_Security($smarty);
// disable all PHP functions
$my_security_policy-&gt;php_functions = null;
// remove PHP tags
$my_security_policy-&gt;php_handling = Smarty::PHP_REMOVE;
// allow everthing as modifier
$my_security_policy-&gt;$modifiers = array();
// enable security
$smarty-&gt;enableSecurity($my_security_policy);
?&gt;

</pre></div>
</div>
<br class="example-break"><div class="example">
<a name="id458213"></a><p class="title"><b>Example 17.3. Enable security with the default settings</b></p>
<div class="example-contents"><pre class="programlisting">

&lt;?php
require 'Smarty.class.php';
$smarty = new Smarty();
// enable default security
$smarty-&gt;enableSecurity();
?&gt;

</pre></div>
</div>
<br class="example-break"><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>
    Must security policy settings are only checked when the template gets compiled. For that reasion you should
    delete all cached and compiled template files when you change your security settings.
  </p>
</div>
</div>
</div>
<div class="navfooter">
<hr>
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left">
<a accesskey="p" href="resources.custom.html">Prev</a> </td>
<td width="20%" align="center"><a accesskey="u" href="smarty.for.programmers.html">Up</a></td>
<td width="40%" align="right"> <a accesskey="n" href="advanced.features.template.settings.html">Next</a>
</td>
</tr>
<tr>
<td width="40%" align="left" valign="top">Custom Template Resources </td>
<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
<td width="40%" align="right" valign="top"> Changing settings by template</td>
</tr>
</table>
</div>
</body>
</html>
